docs(workflows): MCP triggering — tools, flow and trigger settings (PRD-742) - #21
Open
christophebrun-forest wants to merge 1 commit into
Open
docs(workflows): MCP triggering — tools, flow and trigger settings (PRD-742)#21christophebrun-forest wants to merge 1 commit into
christophebrun-forest wants to merge 1 commit into
Conversation
…RD-742) Document the MCP channel added by PRD-49, written from the implementation in the three feature branches rather than from the spec. MCP server page: the three workflow tools (listWorkflows, triggerWorkflow, getWorkflowRun) with their arg/return contracts, the discover -> trigger -> poll flow, and the v1 limitations — no dedicated rate limiter, human-gated runs are report-only. Triggers page: goes from two triggers to three, states that gating is channel-aware, and documents two prerequisites that were missing for the webhook trigger too (Forest Runtime installed, fallback inbox selected). The section is named Triggers, not Process. Screenshot refreshed with the MCP row. Deviations from the spec, followed as implemented: listWorkflows returns no description; getWorkflowRun only exposes MCP-triggered runs; result is the terminal step, not a business payload. Also fixes an unescaped pipe that broke a table in the webhook reference. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![macroscopeapp[bot]](https://avatars.githubusercontent.com/in/900172?s=60&v=4){kind=small}
| The record is **not** checked when the run is created — the orchestrator has no data access at that point. An id that does not exist, or that the user cannot read, produces a run that fails at its first data step; the assistant sees it through `getWorkflowRun`'s `error`, not as a trigger-time failure. | ||
| </Note> | ||
|
|
||
| Only **one run per record** can be active at a time. Triggering a record that already has an ongoing run fails and does **not** resume it — the run in flight is left untouched. |
There was a problem hiding this comment.
🟡 Medium embed/mcp-server.mdx:344
The documentation states "one run per record can be active at a time," but this is stricter than the actual behavior. The webhook trigger allows one active run per workflow per record — running a different workflow on the same record does not conflict. As written, the assistant would avoid triggering a second workflow on a record that already has any run in flight, when in fact only re-triggering the same workflow conflicts.
Suggested change
| Only **one run per record** can be active at a time. Triggering a record that already has an ongoing run fails and does **not** resume it — the run in flight is left untouched. | |
| Only **one run per workflow per record** can be active at a time. Triggering a record that already has an ongoing run of the same workflow fails and does **not** resume it — the run in flight is left untouched. |
🚀 Reply "fix it for me" or copy this AI Prompt for your agent:
In file @product/embed/mcp-server.mdx around line 344:
The documentation states "one run per record can be active at a time," but this is stricter than the actual behavior. The webhook trigger allows one active run **per workflow per record** — running a different workflow on the same record does not conflict. As written, the assistant would avoid triggering a second workflow on a record that already has any run in flight, when in fact only re-triggering the *same* workflow conflicts.
EnkiP
approved these changes
Aug 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the MCP trigger channel shipped by PRD-49, closing the docs half of PRD-742.
Written from the implementation in the three feature branches (front #9870, mcp-server #1792, orchestrator #8418), not from the spec — see Deviations below.
What changed
product/embed/mcp-server.mdx— the bulk of itrunStatetable, JSON examples for a parked and a finished run, an error table, and Identity, auditing, and limits covering the two v1 limitations PRD-742 asks for — no dedicated rate limiter and report-only human-gated runsproduct/process/workflows/triggers.mdx— two triggers → threeAligned neighbours —
overview.mdx,execute/workflows.mdx(automated runs land in the fallback inbox),forest-runtime.mdx(MCP triggering needs the Runtime too). Plus an unescaped pipe that broke a table in the webhook API reference.Deviations from the spec, followed as implemented
listWorkflowsreturns nodescription— onlyworkflowId,name,collectionName. The docs don't promise one.getWorkflowRunis scoped to MCP-triggered runs (triggerType='mcp'in the store query): a manual or webhook run 404s, even for the same user. Not in the spec; documented as a<Warning>.resultis the terminal step ({ name, type, taskType?, context }), not a business payload.runStatereturned bytriggerWorkflowdepends on the workflow's first step, so the docs tell readers not to treat it as an outcome.No-regression verification (2nd AC of PRD-742)
Confirmed by reading the code, not by running it: MCP gating lives in
startWorkflowRunFromMcp, webhook gating inworkflow-webhook-route.ts:106, and the manual/startpath has neither —startWorkflowRunis only touched by an audit-label refactor. Covered byshould not gate the manual /start path (no regression) on an mcp-enabled workflow(workflow-orchestrator-endpoint.test.ts:1161). No symmetric webhook test exists, but the webhook channel never reads themcptoggle.Checks
mint broken-linkspasses.🤖 Generated with Claude Code
Note
Document MCP trigger for workflows including tools, flow, and trigger settings
listWorkflows,triggerWorkflow, andgetWorkflowRun, plus a full guide covering the discover → trigger → poll flow, run state model, constraints, and human-in-the-loop behavior.📊 Macroscope summarized 0a79255. 6 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted
🗂️ Filtered Issues
No issues evaluated.